RESTful API 服务

概述

RESTful API（Representational State Transfer）是一种基于HTTP协议的网络服务架构风格。它通过标准的HTTP方法（如GET、POST、PUT、DELETE）来操作资源，使得客户端和服务器之间的通信更加简洁和规范。在本教程中，我们将使用Django REST framework（DRF）来构建一个RESTful API服务。

安装和环境设置

安装Django和Django REST framework

首先，确保你已经安装了Python和Django。然后，使用pip安装Django REST framework：

pip install djangorestframework

创建Django项目

接下来，创建一个新的Django项目和一个应用：

django-admin startproject myapi
cd myapi
python manage.py startapp api

配置Django REST framework

在myapi/settings.py中，添加rest_framework到INSTALLED_APPS：

INSTALLED_APPS = [
    ...
    'rest_framework',
    'api',
]

序列化器

序列化器用于将复杂的Django模型数据转换为JSON格式，以便在API中传输。

创建序列化器

在api应用中创建一个serializers.py文件，并定义一个序列化器：

from rest_framework import serializers
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = '__all__'

定义模型

在api/models.py中定义一个简单的Product模型：

from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField()
    price = models.DecimalField(max_digits=10, decimal_places=2)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

迁移数据库

运行以下命令来创建数据库表：

python manage.py makemigrations
python manage.py migrate

视图集和路由器

视图集（ViewSets）是DRF中用于处理API视图的高级抽象。路由器（Routers）则用于自动生成URL模式。

创建视图集

在api/views.py中定义一个视图集：

from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

配置路由器

在api/urls.py中配置路由器：

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import ProductViewSet

router = DefaultRouter()
router.register(r'products', ProductViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

配置项目URL

在myapi/urls.py中包含api应用的URL：

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('api.urls')),
]

测试API

启动Django开发服务器：

python manage.py runserver

访问http://127.0.0.1:8000/api/products/，你应该能看到一个空的JSON响应。你可以使用POST请求来添加新的产品，使用GET请求来获取产品列表，使用PUT请求来更新产品，使用DELETE请求来删除产品。

认证和权限

DRF提供了多种认证和权限机制，以确保API的安全性。

配置认证和权限

在myapi/settings.py中配置默认的认证和权限类：

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.BasicAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ]
}

自定义权限

你可以在视图集中自定义权限：

from rest_framework.permissions import BasePermission

class IsOwnerOrReadOnly(BasePermission):
    def has_object_permission(self, request, view, obj):
        if request.method in ['GET', 'HEAD', 'OPTIONS']:
            return True
        return obj.owner == request.user

然后在视图集中应用这个权限：

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    permission_classes = [IsOwnerOrReadOnly]

API版本控制

随着API的发展，你可能需要支持多个版本。DRF提供了多种版本控制机制。

配置版本控制

在myapi/settings.py中配置版本控制：

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
    'ALLOWED_VERSIONS': ['v1', 'v2'],
}

使用版本控制

在URL模式中使用版本控制：

urlpatterns = [
    path('api/<str:version>/products/', include('api.urls')),
]

单元测试

DRF提供了强大的测试工具，帮助你编写和运行API测试。

编写测试

在api/tests.py中编写测试：

from django.urls import reverse
from rest_framework import status
from rest_framework.test import APITestCase
from .models import Product

class ProductTests(APITestCase):
    def test_create_product(self):
        url = reverse('product-list')
        data = {'name': 'Test Product', 'description': 'Test Description', 'price': '9.99'}
        response = self.client.post(url, data, format='json')
        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
        self.assertEqual(Product.objects.count(), 1)
        self.assertEqual(Product.objects.get().name, 'Test Product')

运行测试

运行以下命令来运行测试：

python manage.py test

实践练习

扩展API：为你的API添加一个新的模型（例如Order），并创建相应的序列化器、视图集和路由器。
权限控制：为Order模型添加权限控制，确保只有授权用户可以创建和查看订单。
版本控制：为你的API添加一个新的版本（例如v2），并确保旧版本仍然可用。

总结

通过本教程，你已经学会了如何使用Django REST framework构建一个RESTful API服务。你了解了序列化器、视图集、路由器、认证和权限、API版本控制以及单元测试。继续探索DRF的更多功能，并尝试将其应用到实际项目中。

← Previous: 构建社交网络应用：从零到一